<html>
    <head>
        <style>
            body {
              max-width: 600px;
              margin: 50px auto;
              font-family: Arial;
              font-size: 15px;
              line-height: 1.5em;
            }
            .tip {
              font-size: .8em;
            }
        </style>
    </head>
    <body>

<h1>Stencil UI plugin</h1>

<p>Stencil UI plugin implements a palette of JointJS elements. These elements can be 
dragged onto a paper.</p>

<h2>Install</h2>

<p>Just add <code>joint.ui.stencil.js</code> and <code>joint.ui.stencil.css</code> to your HTML:</p>
<pre><code>
&lt;link href="joint.ui.stencil.css" rel="stylesheet" type="text/css" /&gt;
&lt;script src="joint.ui.stencil.js" type="text/javascript" &gt;&lt;/script&gt;
</code></pre>

<h2>Creating a stencil</h2>

<pre><code>
var graph = new joint.dia.Graph;
var paper = new joint.dia.Paper({
   el: $('#paper'),
   width: 500,
   height: 300,
   gridSize: 20,
   perpendicularLinks: true,
   model: graph
});

var stencil = new joint.ui.Stencil({ 
   graph: graph, 
   paper: paper,
   width: 200,
   height: 300
});
$('#stencil-holder').append(stencil.render().el);
</code></pre>

<p>The <code>joint.ui.Stencil</code> constructor takes graph and paper objects and the dimensions of the stencil
    area. The next thing to do is rendering the stencil widget (<code>stencil.render()</code>) and
    appending the stencil element to a holder which can be any element in your HTML. Please see the demo for
    reference on how to do that if you're in doubts.
</p>


<h2>Populating Stencil with elements</h2>

<pre><code>
var r = new joint.shapes.basic.Rect({ 
    position: { x: 10, y: 10 }, size: { width: 50, height: 30 } 
});
var c = new joint.shapes.basic.Circle({ 
    position: { x: 70, y: 10 }, size: { width: 50, height: 30 } 
});

stencil.load([r, c]);
</code></pre>

<p>As you can see, there is no surprises with populating the stencil with elements. The 
<code>stencil.load()</code> method takes an array of elements as an argument and renders
those elements into the stencil.</p>

<h2>Using groups in Stencil (a.k.a. accordion)</h2>

<p>Creating an accordion-like Stencil is as easy as passing the <code>groups</code> object to the
stencil constructor. <code>groups</code> object is a hash table mapping group identifiers
to the configuration of the particular group. Each group configuration object contains these properties:</p>

<ul>
    <li><code>label</code> - group label.</li>
    <li><code>index</code> - position of the group in the stencil.</li>
    <li><code>closed</code> - [optional] when <code>true</code>, this group will be initially closed.</li>
    <li><code>height</code> - [optional] the height of the paper containing the shapes of the group. If not defined,
        then the height of the stencil will be used. If non of these height are defined, the paper will be automatically scaled to fit its content (recommended).</li>
</ul>

<pre><code>
var stencil = new joint.ui.Stencil({ 
   graph: graph, 
   paper: paper,
   width: 200,
   groups: {
        one: { label: 'First group', index: 1 },
        two: { label: 'Second group', index: 2, closed: true }
   }
});
</code></pre>

<h2>Other methods</h2>

<ul>
    <li><code>getGraph(groupName)</code> - get the graph associated with the group identified by <code>groupName</code>. If the stencil does not use groups, just omit the <code>groupName</code> parameter to get the only graph present.</li>
    <li><code>getPaper(groupName)</code> - get the paper associated with the group identified by <code>groupName</code>. If the stencil does not use groups, just omit the <code>groupName</code> parameter to get the only paper present.</li>
    <li><code>openGroup(groupName)</code> - open group <code>groupName</code>.</li>
    <li><code>closeGroup(groupName)</code> - close group <code>groupName</code>.</li>
    <li><code>toggleGroup(groupName)</code> - toggle group <code>groupName</code>.</li>
    <li><code>openGroups()</code> - open all groups.</li>
    <li><code>closeGroups()</code> - close all groups.</li>
</ul>

<h2>TIP: Reacting on elements added to the paper</h2>

<p>Many times, you might want to perform some action as a reaction on a new element dragged from the
stencil to the paper. This can be achieved by usual means, i.e. by reacting on new elements added to the graph:

<pre><code>
graph.on('add', function(cell) {
   console.log('A cell with id', cell.id, 'was just added to the paper.');
});
</code></pre>
</p>

